home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 2 / Atari Mega Archive CD - Volume 2.iso / 8bit / cislib_b / probj.doc < prev    next >
Text File  |  1995-04-22  |  12KB  |  433 lines
  1.               PROBJ 1.0 
  2.      PRocess OBJect (Load) files. 
  3.        Compiled in ACTION!(tm) 
  4.  
  5. (c)1984 John Navas II 
  6. No commercial use without permission. 
  7.  
  8. OVERVIEW: 
  9.  
  10.    PROBJ is a general purpose utility 
  11. for processing Atari DOS object Load 
  12. files. It's principal capabilities 
  13. are: 
  14.    * To produce a RAM address map of 
  15. the segments in the load file, 
  16. together with the disk address of the 
  17. start of each segment. 
  18.    * To produce a new load file with 
  19. contiguous segments "compressed" into 
  20. a longer segment (which can save disk 
  21. space and speed loading). 
  22.    * To allow one or more segment(s) 
  23. to be deleted from the new load file. 
  24. (Thus a single load file may be broken 
  25. into pieces.) 
  26.    * To ZAP (change) bytes in the new 
  27. load file. (All changes are verified, 
  28. allowing bytes to be examined even if 
  29. no changes are to be made.) 
  30.  
  31. MINIMUM SYSTEM REQUIREMENTS: 
  32.  
  33.    * 24K RAM (48-64K is preferred). 
  34.    * Disk Drive. 
  35.  
  36. FEATURES: 
  37.  
  38.    * PROBJ is in binary Load file form 
  39. (to be run from DOS with OR WITHOUT 
  40. any cartridges). THIS MEANS THAT IT 
  41. MUST BE DOWNLOADED WITH A PROGRAM 
  42. SUPPORTING CIS ERROR-CHECKING, SUCH AS 
  43. TSCOPE. 
  44.    * Dynamic buffer uses all of 
  45. available RAM (buffer size displayed). 
  46.    * Extensive error trapping. 
  47.    * Accepts responses in upper or 
  48. lower case. 
  49.    * Interactive execution with helps 
  50. and prompts. 
  51.    * RAM map may be directed to any 
  52. valid file specification. 
  53.    * RAM map identifies DOS initialize 
  54. and run vectors. 
  55.    * Both RAM addresses and data 
  56. displayed and accepted in hexadecimal 
  57. format. 
  58.    * Disk addresses in decimal format. 
  59.    * Generation of the output file is 
  60. optional. 
  61.  
  62. NOTES: 
  63.  
  64.    * Loads in RAM at $3000 (12K). 
  65. Program size is approximately 8K 
  66. bytes. 
  67.    * Should work with any compatible 
  68. DOS and disk drives. 
  69.    * Will NOT accept tokenized Atari 
  70. BASIC (Saved) programs. 
  71.    * Will not accept ATASCII text 
  72. files. 
  73.  
  74. COMPRESSING OBJECT LOAD FILES: 
  75.  
  76.    All DOS object load files must 
  77. begin with a 2-byte "header" of $FFFF. 
  78. Since one load file can be Appended to 
  79. another with DOS Copy, there can be 
  80. unnecessary headers embedded in a 
  81. file. PROBJ automatically removes 
  82. embedded headers from any output file. 
  83.    An object load file consists of one 
  84. or more load segments. Each segment 
  85. consists of two 2-byte addresses 
  86. giving the beginning and ending RAM 
  87. address for the segment (in 6502 
  88. low-high byte format), followed by the 
  89. data for that segment. Each time DOS 
  90. encounters the end of one segment and 
  91. the beginning of another segment, the 
  92. extra processing required results in a 
  93. delay long enough for the disk drive 
  94. to take an extra revolution. As a 
  95. result, a file containing a number of 
  96. short segments will Load much more 
  97. slowly than a file of equal length 
  98. consisting of a single segment. 
  99.    The problem is that some program 
  100. development tools, most notably the 
  101. Atari Macro Assembler, generate object 
  102. files containing only short segments, 
  103. even if the segments load in 
  104. contiguous RAM addresses. PROBJ will 
  105. combine these contiguous segments into 
  106. a longer segment (buffer size 
  107. permitting), creating a new file which 
  108. should Load faster and may also save 
  109. disk space by the elimination of 
  110. unnecessary 2-byte addresses (and 
  111. headers). 
  112.  
  113. GETTING STARTED: 
  114.  
  115.    For maximum buffer size it is 
  116. recommended that any cartridges be 
  117. removed from your machine. However, 
  118. adequate RAM should be available for 
  119. most object load files even with a 
  120. cartridge installed. (If a buffer 
  121. error message is encountered with a 
  122. cartridge installed during program 
  123. execution on a 48-64K system, remove 
  124. the cartridge and re-try the 
  125. operation!) 
  126.    From your DOS menu, Load PROBJ.BIN 
  127. (unless you've given it a different 
  128. name). As soon as the program Loads, 
  129. the following screen is displayed: 
  130.  
  131. *********************************** 
  132.  
  133. PROBJ 1.0 - Written in ACTION!(tm) 
  134. (C)1984 John Navas II 
  135.  
  136. Input must be a standard DOS object 
  137. Load file. Output will be a RAM map 
  138. and an optional compressed Load file. 
  139. Individual segments may be removed 
  140. from and bytes may be "ZAP" changed 
  141. in the output Load file. 
  142.  
  143. Buffer size = $hhhh 
  144.  
  145. *********************************** 
  146.  
  147.    The actual buffer size appears in 
  148. place of "hhhh". The buffer limits the 
  149. maximum size of a compressed output 
  150. object file segment (see "error 
  151. messages" below). It also limits the 
  152. maximum size of any input object file 
  153. segment which can be processed; if an 
  154. input segment is encountered which 
  155. exceeds the buffer, processing is 
  156. abandoned with an error message (see 
  157. below). 
  158.    PROBJ first asks: 
  159.  
  160.    FILE SPEC for RAM map? (E:) 
  161.  
  162.    If you want your map to appear on 
  163. your screen, merely press <RETURN>. 
  164. You may direct it to your printer by 
  165. typing P<RETURN>. In fact you may type 
  166. any valid file specification (although 
  167. interactive operation can be difficult 
  168. if the map is not visible!). If the 
  169. file cannot be opened successfully, 
  170. PROBJ responds "CANNOT OPEN FILE!" and 
  171. prompts you to try again. If the file 
  172. is opened to a device other than the 
  173. screen editor (E:), a title with the 
  174. input file name will be placed before 
  175. the map. 
  176.    Next PROBJ prompts you with: 
  177.  
  178.    Input FILE SPEC? 
  179.  
  180.    First, make sure that the disk 
  181. containing the input file is in your 
  182. disk drive! Then type the file 
  183. specification of the input file you 
  184. wish to process. (If your file is on 
  185. disk drive #1, you may omit the "D:".) 
  186. Again, you will get an error message 
  187. and be prompted to try again if the 
  188. file cannot be opened. 
  189.    Next you will see: 
  190.  
  191.    Output FILE SPEC? 
  192.  
  193.    If you want only a RAM map, and not 
  194. an output file, merely press <RETURN>. 
  195. Otherwise, first make sure that you 
  196. have a disk in your drive with 
  197. sufficient room to accomodate the 
  198. output file! Then type the file 
  199. specification of the output file to be 
  200. created. (If your file is on disk 
  201. drive #1, you may omit the "D:".) 
  202. Again, you will get an error message 
  203. and be prompted to try again if the 
  204. file cannot be opened. 
  205.    If (and only if) you are creating 
  206. an output file, PROBJ will next give 
  207. the following two prompts: 
  208.  
  209.    Remove output segments? (Y/N) 
  210.    ZAP (change) bytes? (Y/N) 
  211.  
  212.    In each case, only press a key to 
  213. give your answer (do NOT press 
  214. <RETURN>). PROBJ will confirm your 
  215. choice by displaying "YES" or "NO". 
  216.    Processing now begins. PROBJ first 
  217. looks for the DOS $FFFF header in the 
  218. input file and abandons processing 
  219. with an error message if one is not 
  220. found (see "error messages" below). 
  221.    Any time a DOS header is 
  222. encountered, PROBJ will display: 
  223.  
  224.    HEADER AT SCTR 88, BYTE 99 
  225.  
  226.    88 and 99 will of course be 
  227. replaced with the actual disk address 
  228. (in decimal) of the first byte of the 
  229. header. 
  230.    Any time a segment is encountered, 
  231. PROBJ first checks to see if the 
  232. segment is contiguous with the last 
  233. segment. If it is, PROBJ will display: 
  234.  
  235.    CONTIGUOUS: 
  236.  
  237.    Next, PROBJ will map the segment by 
  238. displaying: 
  239.  
  240.    SEG $hhhh-$iiii AT SCTR 88, BYTE 99 
  241.  
  242.    $hhhh will be replaced with the 
  243. actual beginning RAM address and $iiii 
  244. will be replaced with the actual 
  245. ending RAM address. As before, 88 and 
  246. 99 will be replaced with the actual 
  247. disk address (in decimal) of the first 
  248. (low) byte of the first address. 
  249.    If the segment is contiguous, PROBJ 
  250. then checks to see if it will fit in 
  251. the remaining buffer space. If it 
  252. won't, this particular segment won't 
  253. be compressed, but processing will 
  254. continue after the message: 
  255.  
  256.    WON'T FIT IN BUFFER, CAN'T COMPRESS 
  257.  
  258.    If the segment contained a DOS 
  259. initialize and/or run vector, the 
  260. vector HEXADECIMAL address will be 
  261. displayed on the map. (INITAD is the 
  262. initialize address; RUNAD is the run 
  263. address.) 
  264.    At the completion of successful 
  265. processing, PROBJ displays the 
  266. message: 
  267.  
  268.    File processed OK! 
  269.  
  270.    However, if an error occurred, 
  271. PROBJ will display (in addition to the 
  272. error message): 
  273.  
  274.    PROCESSING FAILED! 
  275.  
  276.    Note: Even though processing fails, 
  277. PROBJ may still have created an output 
  278. file, but the file will usually not be 
  279. valid! 
  280.  
  281.    Finally, PROBJ will ask: 
  282.  
  283.    Another file? (Y/N) 
  284.  
  285.    As before, press a key (not 
  286. <RETURN>). If you press anything other 
  287. than "Y", PROBJ will return to DOS. 
  288. Note